<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.9.4"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Flow-IPC: ipc::transport::Native_handle_sender Class Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">Flow-IPC<span id="projectnumber">&#160;1.0.2</span>
   </div>
   <div id="projectbrief">Flow-IPC project: Full implementation reference.</div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.9.4 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search",'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() {
  initMenu('',true,false,'search.php','Search');
  $(document).ready(function() { init_search(); });
});
/* @license-end */
</script>
<div id="main-nav"></div>
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0" 
        name="MSearchResults" id="MSearchResults">
</iframe>
</div>

<div id="nav-path" class="navpath">
  <ul>
<li class="navelem"><a class="el" href="namespaceipc.html">ipc</a></li><li class="navelem"><a class="el" href="namespaceipc_1_1transport.html">transport</a></li><li class="navelem"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html">Native_handle_sender</a></li>  </ul>
</div>
</div><!-- top -->
<div class="header">
  <div class="summary">
<a href="#pub-methods">Public Member Functions</a> &#124;
<a href="#pub-static-attribs">Static Public Attributes</a> &#124;
<a href="classipc_1_1transport_1_1Native__handle__sender-members.html">List of all members</a>  </div>
  <div class="headertitle"><div class="title">ipc::transport::Native_handle_sender Class Reference</div></div>
</div><!--header-->
<div class="contents">

<p>A documentation-only <em>concept</em> defining the behavior of an object capable of reliably/in-order <em>sending</em> of discrete messages, each containing a native handle, a binary blob, or both.  
 <a href="classipc_1_1transport_1_1Native__handle__sender.html#details">More...</a></p>

<p><code>#include &lt;<a class="el" href="native__handle__transport_8hpp_source.html">native_handle_transport.hpp</a>&gt;</code></p>
<div class="dynheader">
Collaboration diagram for ipc::transport::Native_handle_sender:</div>
<div class="dyncontent">
<div class="center"><iframe scrolling="no" frameborder="0" src="classipc_1_1transport_1_1Native__handle__sender__coll__graph.svg" width="356" height="372"><p><b>This browser is not able to show SVG: try Firefox, Chrome, Safari, or Opera instead.</b></p></iframe>
</div>
<center><span class="legend">[<a href="graph_legend.html">legend</a>]</span></center></div>
<table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-methods" name="pub-methods"></a>
Public Member Functions</h2></td></tr>
<tr class="memitem:abafdb9a1294fe2160c61d48f1cd327ff"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#abafdb9a1294fe2160c61d48f1cd327ff">Native_handle_sender</a> ()</td></tr>
<tr class="memdesc:abafdb9a1294fe2160c61d48f1cd327ff"><td class="mdescLeft">&#160;</td><td class="mdescRight">Default ctor: Creates a peer object in NULL (neither connected nor connecting) state.  <a href="classipc_1_1transport_1_1Native__handle__sender.html#abafdb9a1294fe2160c61d48f1cd327ff">More...</a><br /></td></tr>
<tr class="separator:abafdb9a1294fe2160c61d48f1cd327ff"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a616a05a623410acde1fc225cbc22f03f"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a616a05a623410acde1fc225cbc22f03f">Native_handle_sender</a> (<a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__handle__sender.html">sync_io::Native_handle_sender</a> &amp;&amp;sync_io_core_in_peer_state_moved)</td></tr>
<tr class="memdesc:a616a05a623410acde1fc225cbc22f03f"><td class="mdescLeft">&#160;</td><td class="mdescRight"><code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code>-core-adopting ctor: Creates a peer object in PEER state by subsuming a <code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code> core in that state.  <a href="classipc_1_1transport_1_1Native__handle__sender.html#a616a05a623410acde1fc225cbc22f03f">More...</a><br /></td></tr>
<tr class="separator:a616a05a623410acde1fc225cbc22f03f"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a4348f5448609ef83c53a161e472f85d5"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a4348f5448609ef83c53a161e472f85d5">Native_handle_sender</a> (<a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html">Native_handle_sender</a> &amp;&amp;src)</td></tr>
<tr class="memdesc:a4348f5448609ef83c53a161e472f85d5"><td class="mdescLeft">&#160;</td><td class="mdescRight">Move-constructs from <code>src</code>; <code>src</code> becomes as-if default-cted (therefore in NULL state).  <a href="classipc_1_1transport_1_1Native__handle__sender.html#a4348f5448609ef83c53a161e472f85d5">More...</a><br /></td></tr>
<tr class="separator:a4348f5448609ef83c53a161e472f85d5"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a531e4ea9d23cbcb1c456b51b5fa2dca1"><td class="memItemLeft" align="right" valign="top"><a id="a531e4ea9d23cbcb1c456b51b5fa2dca1" name="a531e4ea9d23cbcb1c456b51b5fa2dca1"></a>
&#160;</td><td class="memItemRight" valign="bottom"><b>Native_handle_sender</b> (const <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html">Native_handle_sender</a> &amp;)=delete</td></tr>
<tr class="memdesc:a531e4ea9d23cbcb1c456b51b5fa2dca1"><td class="mdescLeft">&#160;</td><td class="mdescRight">Disallow copying. <br /></td></tr>
<tr class="separator:a531e4ea9d23cbcb1c456b51b5fa2dca1"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aa2354a74bc6cdff9389d0b7b642fbadd"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#aa2354a74bc6cdff9389d0b7b642fbadd">~Native_handle_sender</a> ()</td></tr>
<tr class="memdesc:aa2354a74bc6cdff9389d0b7b642fbadd"><td class="mdescLeft">&#160;</td><td class="mdescRight">Destroys this peer endpoint which will end the conceptual outgoing-direction pipe (in PEER state, and if it's still active) and cancels any pending completion handlers by invoking them ASAP with <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297afe29343445a7bf167cc186a44bd2c6ed" title="Async completion handler is being called prematurely, because underlying object is shutting down,...">error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER</a>.  <a href="classipc_1_1transport_1_1Native__handle__sender.html#aa2354a74bc6cdff9389d0b7b642fbadd">More...</a><br /></td></tr>
<tr class="separator:aa2354a74bc6cdff9389d0b7b642fbadd"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a7de1a7f689cfdd926580cf92131896bb"><td class="memItemLeft" align="right" valign="top"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html">Native_handle_sender</a> &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a7de1a7f689cfdd926580cf92131896bb">operator=</a> (<a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html">Native_handle_sender</a> &amp;&amp;src)</td></tr>
<tr class="memdesc:a7de1a7f689cfdd926580cf92131896bb"><td class="mdescLeft">&#160;</td><td class="mdescRight">Move-assigns from <code>src</code>; <code>*this</code> acts as if destructed; <code>src</code> becomes as-if default-cted (therefore in NULL state).  <a href="classipc_1_1transport_1_1Native__handle__sender.html#a7de1a7f689cfdd926580cf92131896bb">More...</a><br /></td></tr>
<tr class="separator:a7de1a7f689cfdd926580cf92131896bb"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a9a784cf71488184323a79695d45adf2e"><td class="memItemLeft" align="right" valign="top"><a id="a9a784cf71488184323a79695d45adf2e" name="a9a784cf71488184323a79695d45adf2e"></a>
<a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html">Native_handle_sender</a> &amp;&#160;</td><td class="memItemRight" valign="bottom"><b>operator=</b> (const <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html">Native_handle_sender</a> &amp;)=delete</td></tr>
<tr class="memdesc:a9a784cf71488184323a79695d45adf2e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Disallow copying. <br /></td></tr>
<tr class="separator:a9a784cf71488184323a79695d45adf2e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a74452bf96477a7b971e187c67703e8d5"><td class="memItemLeft" align="right" valign="top">size_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a74452bf96477a7b971e187c67703e8d5">send_meta_blob_max_size</a> () const</td></tr>
<tr class="memdesc:a74452bf96477a7b971e187c67703e8d5"><td class="mdescLeft">&#160;</td><td class="mdescRight">In PEER state: Returns max <code>meta_blob.size()</code> such that <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> shall not fail due to too-long payload with <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297ac416e988563e44bf15fc6a81743eef53" title="User called an API with 1 or more arguments against the API spec.">error::Code::S_INVALID_ARGUMENT</a>.  <a href="classipc_1_1transport_1_1Native__handle__sender.html#a74452bf96477a7b971e187c67703e8d5">More...</a><br /></td></tr>
<tr class="separator:a74452bf96477a7b971e187c67703e8d5"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ac96b0aa01c286d525f9dcfa6dacc4220"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220">send_native_handle</a> (<a class="el" href="namespaceipc_1_1transport.html#a7ee4551983d9df16ec16a3139bac50e8">Native_handle</a> hndl_or_null, const <a class="el" href="namespaceipc_1_1util.html#ae0be7edba7e30ffa3f8b742af621f2ab">util::Blob_const</a> &amp;meta_blob, <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *err_code=0)</td></tr>
<tr class="memdesc:ac96b0aa01c286d525f9dcfa6dacc4220"><td class="mdescLeft">&#160;</td><td class="mdescRight">In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order, to the opposing peer; the message consists of the provided native handle (if supplied); or the provided binary blob (if supplied); or both (if both supplied).  <a href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220">More...</a><br /></td></tr>
<tr class="separator:ac96b0aa01c286d525f9dcfa6dacc4220"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a4c92fe4e43ddf819a2c767cc53cbe477"><td class="memTemplParams" colspan="2">template&lt;typename Task_err &gt; </td></tr>
<tr class="memitem:a4c92fe4e43ddf819a2c767cc53cbe477"><td class="memTemplItemLeft" align="right" valign="top">bool&#160;</td><td class="memTemplItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a4c92fe4e43ddf819a2c767cc53cbe477">async_end_sending</a> (Task_err &amp;&amp;on_done_func)</td></tr>
<tr class="memdesc:a4c92fe4e43ddf819a2c767cc53cbe477"><td class="mdescLeft">&#160;</td><td class="mdescRight">Equivalent to <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> but sends a graceful-close message instead of the usual payload; the opposing peer's <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a> shall receive it reliably and in-order via <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">Native_handle_receiver::async_receive_native_handle()</a> in the form of <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> = <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297aad44f87d53255ba573d57086dfeab805" title="Will not receive message: either opposing user sent graceful-close via API.">error::Code::S_RECEIVES_FINISHED_CANNOT_RECEIVE</a>.  <a href="classipc_1_1transport_1_1Native__handle__sender.html#a4c92fe4e43ddf819a2c767cc53cbe477">More...</a><br /></td></tr>
<tr class="separator:a4c92fe4e43ddf819a2c767cc53cbe477"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aa3c2953f7f8a48b8a0cbf49652fb6d41"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#aa3c2953f7f8a48b8a0cbf49652fb6d41">end_sending</a> ()</td></tr>
<tr class="memdesc:aa3c2953f7f8a48b8a0cbf49652fb6d41"><td class="mdescLeft">&#160;</td><td class="mdescRight">Equivalent to <code>async_end_sending(F)</code> wherein <code>F()</code> does nothing.  <a href="classipc_1_1transport_1_1Native__handle__sender.html#aa3c2953f7f8a48b8a0cbf49652fb6d41">More...</a><br /></td></tr>
<tr class="separator:aa3c2953f7f8a48b8a0cbf49652fb6d41"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a8a2f1282c18faec36aabf29c99b87054"><td class="memItemLeft" align="right" valign="top">bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a8a2f1282c18faec36aabf29c99b87054">auto_ping</a> (<a class="el" href="namespaceipc_1_1util.html#ac66141280c3b7295a86b65209f31cc58">util::Fine_duration</a> period=default_value)</td></tr>
<tr class="memdesc:a8a2f1282c18faec36aabf29c99b87054"><td class="mdescLeft">&#160;</td><td class="mdescRight">In PEER state: Irreversibly enables periodic auto-pinging of opposing receiver with low-level messages that are ignored except that they reset any idle timer as enabled via <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a174ee15818a8bda361bdc40f094faac9" title="In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is,...">Native_handle_receiver::idle_timer_run()</a> (or similar).  <a href="classipc_1_1transport_1_1Native__handle__sender.html#a8a2f1282c18faec36aabf29c99b87054">More...</a><br /></td></tr>
<tr class="separator:a8a2f1282c18faec36aabf29c99b87054"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a id="pub-static-attribs" name="pub-static-attribs"></a>
Static Public Attributes</h2></td></tr>
<tr class="memitem:a840003f2f91ef73f319e0e6b5e7ab435"><td class="memItemLeft" align="right" valign="top">static const <a class="el" href="namespaceipc_1_1transport.html#a33de1c256addb3964b839dc2dd407d24">Shared_name</a>&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a840003f2f91ef73f319e0e6b5e7ab435">S_RESOURCE_TYPE_ID</a></td></tr>
<tr class="memdesc:a840003f2f91ef73f319e0e6b5e7ab435"><td class="mdescLeft">&#160;</td><td class="mdescRight">Shared_name relative-folder fragment (no separators) identifying this resource type. Equals <code>_receiver</code>'s.  <a href="classipc_1_1transport_1_1Native__handle__sender.html#a840003f2f91ef73f319e0e6b5e7ab435">More...</a><br /></td></tr>
<tr class="separator:a840003f2f91ef73f319e0e6b5e7ab435"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p >A documentation-only <em>concept</em> defining the behavior of an object capable of reliably/in-order <em>sending</em> of discrete messages, each containing a native handle, a binary blob, or both. </p>
<p >This is paired with the <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a> concept which defines reception of such messages.</p>
<h3>Concept contents</h3>
<p >The concept defines the following behaviors/requirements.</p><ul>
<li>The object has at least 2 states:<ul>
<li>NULL: Object is not a peer: is not connected/capable of transmission. Essentially it is not a useful state. A default-cted object is in NULL state; and a moved-from object is as-if default-cted, therefore also in a NULL state. In this state all the transmission methods return <code>false</code> and no-op.</li>
<li>PEER: Object is or has been a peer (connected/capable of transmission). It is not possible to exit PEER state, except via being moved-from. A pipe-hosing error retains PEER state for instance.</li>
<li>Other states are allowed but outside the scope of the concept. For example a CONNECTING state may or may not be relevant (but again not relevant to the concept).</li>
</ul>
</li>
<li>The (outgoing) transmission-of-messages methods, including transmission of graceful-close message. See their doc headers.</li>
<li>Behavior when the destructor is invoked. See <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#aa2354a74bc6cdff9389d0b7b642fbadd" title="Destroys this peer endpoint which will end the conceptual outgoing-direction pipe (in PEER state,...">~Native_handle_sender()</a> doc header.</li>
<li>Default ctor (which creates a NULL-state object that can be moved-to and to which "as-if" state any moved-from object is changed).</li>
<li><code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code>-core adopting ctor (which creates PEER-state object from an idle, as-if-just cted PEER-state <a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object that is the sync_io-pattern counterpa...">sync_io::Native_handle_sender</a>).</li>
<li>Move ctor, move assigment operator; these do the reasonable thing including setting the moved-from object to NULL state. Various satellite APIs (e.g., <a class="el" href="classipc_1_1transport_1_1Native__socket__stream__acceptor.html" title="A server object that binds to a Shared_name and listens for incoming Native_socket_stream connect att...">Native_socket_stream_acceptor</a>) shall need these. That is such APIs do not rely on the factory/shared-ownership pattern.</li>
</ul>
<p >The concept (intentionally) does <em>not</em> define the following behaviors:</p><ul>
<li>How to create a <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a>, except the default, <code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code>-core-adopting, and move ctors. That is it does not define how to create a <em>new</em> (not moved-from) and <em>functioning</em> (PEER state: transmitting, connected) peer object, except the latter from an existing <code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code>-pattern core. It only defines behavior once the user has access to a <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> that is already in PEER state: connected to a opposing peer <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a>.</li>
</ul>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="classipc_1_1transport_1_1Native__socket__stream.html" title="Implements both Native_handle_sender and Native_handle_receiver concepts by using a stream-oriented U...">Native_socket_stream</a>: as of this writing one key class that implements this concept (and also <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a>) &ndash; using the Unix domain socket <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">transport</a>. </dd>
<dd>
<a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">Channel</a>, a pipe-composing class template that potentially implements this concept. </dd>
<dd>
<a class="el" href="classipc_1_1transport_1_1Blob__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Blob_sender</a>: a degenerate version of the present concept: capable of transmitting only blobs, not <code><a class="el" href="namespaceipc_1_1transport.html#a7ee4551983d9df16ec16a3139bac50e8" title="Convenience alias for the commonly used type util::Native_handle.">Native_handle</a></code>s.</dd></dl>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000008">Todo:</a></b></dt><dd>In C++20, if/when we upgrade to that, <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> (and other such doc-only classes) can become an actual concept formally implemented by class(es) that, today, implement it via the "honor system." Currently it is a class <code>#ifdef</code>-ed out from actual compilation but still participating in doc generation. Note that Doxygen (current version as of this writing: 1.9.3) claims to support doc generation from formal C++20 concepts.</dd></dl>
<h3>Rationale: Why is <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> not asynchronous?</h3>
<p ><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a>, as noted in its doc header (and similarly <a class="el" href="classipc_1_1transport_1_1Blob__sender.html#a776b55ae93e65592b90c3943ca99e948" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably and in-order,...">Blob_sender::send_blob()</a>) has 2 key properties:</p><ul>
<li>It will <em>never</em> return would-block despite <em>always</em> being non-blocking.</li>
<li>It takes no completion handler; and it returns pipe-hosing errors synchronously via an out-arg or exception.<ul>
<li><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a4c92fe4e43ddf819a2c767cc53cbe477" title="Equivalent to send_native_handle() but sends a graceful-close message instead of the usual payload; t...">async_end_sending()</a> does take a completion handler.</li>
</ul>
</li>
</ul>
<p >That is, it is "somehow" both non-blocking/synchronous &ndash; yet requires no would-block contingency on the user's part. Magical! How can this possibly work? After all we know that all known low-level transports will yield would-block eventually (as of this writing &ndash; Unix domain sockets, POSIX MQs, bipc SHM-based MQs), if the opposing side is not popping data off the pipe. Yet, as we look at the opposing <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a> concept we see that it makes no requirement on its impls to pop everything off the low-level transport in-pipe as soon as it arrives. (In actual fact all existing impls in Flow-IPC refuse to do any such thing.)</p>
<p >Naturally the only answer as to how it can work is: Any given <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> (and native <a class="el" href="classipc_1_1transport_1_1Blob__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Blob_sender</a>) impl shall be ready to encounter would-block internally; if this occurs it will need to make a copy of the offending message (the meta-blob part specifically included &ndash; that's the part that involves significant copying), enqueue it internally &ndash; and keep enqueuing any further <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a>d messages until the would-block clears, and the queue is eventually emptied.</p>
<p >Fair enough: But isn't this a performance hazard? Answer: yes but only in a necessary way. We reached this decision after considering the entire system end-to-end:</p><ol type="1">
<li>user prepares message blob B and tells <code><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a></code> S to send B;</li>
<li>S tells low-level transport (possibly kernel) to accept B;</li>
<li><code><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a></code> R pops B from low-level transport;</li>
<li>user tells R it wanst to accept B, and R does give the latter to the user.</li>
</ol>
<p >It was a no-go to have Flow-IPC be in charge of allocating either-end buffer for B on the user's behalf: the user may want to user their own allocator, or the stack, or ??? &ndash; possibly with zero-copy and prefix/postfix data nearby. The user buffer has to be ready, and S and R need to work with the memory areas provided by the user.</p>
<p >Given all that, <em>one</em> or more of the following "people" has to be ready to keep B, or a copy of B, around, until the whole thing (1-4) has gone through: the sending user (1 above), S (2 above), or R (3 above). (If the receiving user (4 above) is always receiving things ASAP, without that process being processor-pegged or something, then it won't be a problem: no copying is necessary, except in step 2 when B is copied into the low-level process. Indeed that should be the case usually; we are discussing what to do <em>if</em> something goes wrong, or the receivier application is mis-coded, or who knows &ndash; the receiver just isn't quick enough.)</p>
<p >The answer, as already noted: <em>One</em> or more of 1, 2, 3 has to make a copy of B long enough until 4 has received it. At that point, in terms of overall performance, it <em>which</em> one of 1, 2, 3 it should be. Upon deliberating a few options occurred, but it seemed clear enough that 1 (original user) should not be the done, if it can be helped. IPC is not networking; as an end user I expect sending an out-message to work synchronously. Making me worry about a completion handler complicates the outgoing-direction API hugely &ndash; and not in a way that makes the incoming-direction API any simpler, since that one always has to be ready for would-block (i.e., no in-messages immediately ready &ndash; an async-receive API is required).</p>
<p >So that left 2 or 3. I (ygoldfel) simply made the decision that one has to be chosen, and of those 2 is earlier and (internally for the concept implementer, also me at the time) more straightforward. If 3 were always reading items out of the low-level transport &ndash; even when the user was not invoking <code>async_receive_*()</code> &ndash; then it would have to at least sometimes make copies of incoming data before the user chose to pop them out. By contrast, queueing it &ndash; only on would-block &ndash; in 2 would effectively make it a last-resort activity, as it should be.</p>
<p >To summarize: Perfect opposing-receiver behavior cannot be guaranteed, and the low-level transport will eventually have a limit as to how much data it can buffer =&gt; in that case some entity must make a copy of the overflowing data =&gt; we want to make life easier for end user, so that entity should not be them =&gt; it must be either the <code>*_sender</code> or <code>*_receiver</code> =&gt; we chose <code>*_sender</code>, because it is safer and easier and faster and a last resort.</p>
<p >One arguable drawback of this API design is that the <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> (and <a class="el" href="classipc_1_1transport_1_1Blob__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Blob_sender</a>) user won't be informed of an out-pipe-hosing error quite as soon as that object itself would know of it &ndash; in some (rare) cases. I.e., if some data are queued up during would-block, and the user has stopped doing <code>send_*()</code> (as far as she is concerned, they're all working fine and have succeeded), and some timer later <code>*this</code> determines (in the background now) that the transport is hosed, the user would only find out about it upon the next <code>send_*()</code> call (it would <em>then</em> return the <code>Error_code</code> immediately), if any, or via <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a4c92fe4e43ddf819a2c767cc53cbe477" title="Equivalent to send_native_handle() but sends a graceful-close message instead of the usual payload; t...">async_end_sending()</a>. Is this really a problem? Answer: Just... no. Exercise in reasoning this out (granted it is <em>somewhat</em> subjective) left to the reader. (Note we <em>could</em> supply some kind of out-of-band on-any-send-error API, and we considered this. It just was not worth it: inelegant, annoying. <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a4c92fe4e43ddf819a2c767cc53cbe477" title="Equivalent to send_native_handle() but sends a graceful-close message instead of the usual payload; t...">async_end_sending()</a> with its completion handler is well sufficient.)</p>
<p >It should be noted that this decision to make <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> synchronous/non-blocking/never-would-blocking has percolated through much of <a class="el" href="namespaceipc_1_1transport.html" title="Flow-IPC module providing transmission of structured messages and/or low-level blobs (and more) betwe...">ipc::transport</a> and even <a class="el" href="namespaceipc_1_1session.html" title="Flow-IPC module providing the broad lifecycle and shared-resource organization – via the session conc...">ipc::session</a>: all our impls; <a class="el" href="classipc_1_1transport_1_1Blob__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Blob_sender</a> and all its impls; <a class="el" href="classipc_1_1transport_1_1Channel.html" title="Peer to a bundle of 1-2 full-duplex pipe(s), one for transmitting unstructured binary blobs; the othe...">Channel</a>; and quite significantly <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html" title="Owning and wrapping a pre-connected transport::Channel peer (an endpoint of an established channel ov...">struc::Channel</a>. You'll note <a class="el" href="classipc_1_1transport_1_1struc_1_1Channel.html#ae645cb58ad9ea6374970f1f32c5da448" title="In the synchronous/non-blocking manner of Blob_sender::send_blob() or Native_handle_sender::send_nati...">struc::Channel::send()</a> is also synchronous/non-blocking/never-would-blocking, and even its implementation at the stage of actually sending binary data via Native_handle_sender/Blob_sender is quite straightforward. In Flow-IPC a <code>send*()</code> "just works."</p>
<dl class="todo"><dt><b><a class="el" href="todo.html#_todo000009">Todo:</a></b></dt><dd>Comparing <a class="el" href="classipc_1_1transport_1_1Blob__sender.html#af5d889f8a209353b3d69f70b44a2095c" title="In PEER state: Returns max blob.size() such that send_blob() shall not fail due to too-long payload w...">Blob_sender::send_blob_max_size()</a> (and similar checks in that family of concepts) to test whether the object is in PEER state is easy enough, but perhaps we can have a utility that would more expressively describe this check: <code>in_peer_state()</code> free function or something? It can still use the same technique internally. </dd></dl>

<p class="definition">Definition at line <a class="el" href="native__handle__transport_8hpp_source.html#l00159">159</a> of file <a class="el" href="native__handle__transport_8hpp_source.html">native_handle_transport.hpp</a>.</p>
</div><h2 class="groupheader">Constructor &amp; Destructor Documentation</h2>
<a id="abafdb9a1294fe2160c61d48f1cd327ff" name="abafdb9a1294fe2160c61d48f1cd327ff"></a>
<h2 class="memtitle"><span class="permalink"><a href="#abafdb9a1294fe2160c61d48f1cd327ff">&#9670;&nbsp;</a></span>Native_handle_sender() <span class="overload">[1/3]</span></h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">ipc::transport::Native_handle_sender::Native_handle_sender </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Default ctor: Creates a peer object in NULL (neither connected nor connecting) state. </p>
<p >In this state, all transmission-related methods (e.g., <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a>) shall return <code>false</code> and otherwise no-op (aside from possible logging).</p>
<p >This ctor is informally intended for the following uses:</p><ul>
<li>A moved-from <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> (i.e., the <code>src</code> arg for move-ctor and move-assignment operator) becomes as-if defaulted-constructed.</li>
<li>A target <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> for a factory-like method (such as <a class="el" href="classipc_1_1transport_1_1Native__socket__stream__acceptor.html#a81426af495ba5a9c832d1ba35fe23ba5" title="Asynchronously awaits for a peer connection to be established and calls on_done_func(),...">Native_socket_stream_acceptor::async_accept()</a>) shall typically be default-cted by the callin guse. (E.g.: <a class="el" href="classipc_1_1transport_1_1Native__socket__stream__acceptor.html" title="A server object that binds to a Shared_name and listens for incoming Native_socket_stream connect att...">Native_socket_stream_acceptor</a> shall asynchronously move-assign a logger-apointed, nicely-nicknamed into that target <code>*this</code>, typically default-cted.)</li>
</ul>
<h3>Informal corollary &ndash; ctor that begins in PEER state</h3>
<p >Any functioning <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> shall need at least one ctor that starts <code>*this</code> directly in PEER state. In that state the transmission-related methods (e.g., <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a>) shall <em>not</em> return <code>false</code> and will in fact attempt transmission. However the form and function of such ctors is entirely dependent on the nature of the low-level transmission medium being encapsulated and is hence <em>intentionally</em> not a part of the concept. That said there is the <code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code>-core-adopting ctor as well which <em>is</em> part of the concept.</p>
<h3>Informal corollary &ndash; NULL-state ctors with 1+ args</h3>
<p >Other, 1+ arg, ctors that similarly create a NULL-state peer object are allowed/encouraged where relevant. In particular one taking a <code>Logger*</code> and a <code>nickname</code> string &ndash; so as to subsequently enter a connecting phase via an <code>*_connect()</code> method, on the way to PEER state &ndash; is reasonable. However this is not a formal part of this concept and is arguably not a general behavior. Such a ctor is informally intended for the following use at least:</p><ul>
<li>One creates a <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> that is <code>Logger</code>-appointed and nicely-<code>nickname</code>d; then one calls <code>*_connect()</code> on it in order to move it to a connecting phase and, hopefully, PEER state in that order. It will retain the logger and nickname (or whatever) throughout. </li>
</ul>

</div>
</div>
<a id="a616a05a623410acde1fc225cbc22f03f" name="a616a05a623410acde1fc225cbc22f03f"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a616a05a623410acde1fc225cbc22f03f">&#9670;&nbsp;</a></span>Native_handle_sender() <span class="overload">[2/3]</span></h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">ipc::transport::Native_handle_sender::Native_handle_sender </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="classipc_1_1transport_1_1sync__io_1_1Native__handle__sender.html">sync_io::Native_handle_sender</a> &amp;&amp;&#160;</td>
          <td class="paramname"><em>sync_io_core_in_peer_state_moved</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p><code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code>-core-adopting ctor: Creates a peer object in PEER state by subsuming a <code><a class="el" href="namespaceipc_1_1transport_1_1sync__io.html" title="sync_io-pattern counterparts to async-I/O-pattern object types in parent namespace ipc::transport.">sync_io</a></code> core in that state. </p>
<p >That core must be as-if-just-cted (having performed no work and not been configured via <code>.start_*_ops()</code>). That core object becomes as-if default-cted (therefore in NULL state).</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">sync_io_core_in_peer_state_moved</td><td>See above. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="a4348f5448609ef83c53a161e472f85d5" name="a4348f5448609ef83c53a161e472f85d5"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a4348f5448609ef83c53a161e472f85d5">&#9670;&nbsp;</a></span>Native_handle_sender() <span class="overload">[3/3]</span></h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">ipc::transport::Native_handle_sender::Native_handle_sender </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html">Native_handle_sender</a> &amp;&amp;&#160;</td>
          <td class="paramname"><em>src</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Move-constructs from <code>src</code>; <code>src</code> becomes as-if default-cted (therefore in NULL state). </p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">src</td><td>Source object. For reasonable uses of <code>src</code> after this ctor returns: see default ctor doc header. </td></tr>
  </table>
  </dd>
</dl>

</div>
</div>
<a id="aa2354a74bc6cdff9389d0b7b642fbadd" name="aa2354a74bc6cdff9389d0b7b642fbadd"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aa2354a74bc6cdff9389d0b7b642fbadd">&#9670;&nbsp;</a></span>~Native_handle_sender()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">ipc::transport::Native_handle_sender::~Native_handle_sender </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Destroys this peer endpoint which will end the conceptual outgoing-direction pipe (in PEER state, and if it's still active) and cancels any pending completion handlers by invoking them ASAP with <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297afe29343445a7bf167cc186a44bd2c6ed" title="Async completion handler is being called prematurely, because underlying object is shutting down,...">error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER</a>. </p>
<p >As of this writing these are the completion handlers that would therefore be called:</p><ul>
<li>The handler passed to <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a4c92fe4e43ddf819a2c767cc53cbe477" title="Equivalent to send_native_handle() but sends a graceful-close message instead of the usual payload; t...">async_end_sending()</a>, if it was not <code>.empty()</code> and has not yet been invoked. Since it is not valid to call <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a4c92fe4e43ddf819a2c767cc53cbe477" title="Equivalent to send_native_handle() but sends a graceful-close message instead of the usual payload; t...">async_end_sending()</a> more than once, there is at most 1 of these.</li>
</ul>
<p >The pending completion handler will be called from an unspecified thread that is not the calling thread. Any associated captured state for that handler will be freed shortly after the handler returns.</p>
<p >We informally but very strongly recommend that your completion handler immediately return if the <code>Error_code</code> passed to it is <code><a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297afe29343445a7bf167cc186a44bd2c6ed" title="Async completion handler is being called prematurely, because underlying object is shutting down,...">error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER</a></code>. This is similar to what one should do when using boost.asio and receiving the conceptually identical <code>operation_aborted</code> error code to an <code>async_...()</code> completion handler. In both cases, this condition means, "we have decided to shut this thing down,
so the completion handlers are simply being informed of this."</p>
<p >In NULL state the dtor shall no-op.</p>
<h3>Thread safety</h3>
<p >Same as for the transmission methods. <em>Plus</em> it is not safe to call this from within a completion handler supplied to one of those methods on the same <code>*this</code>. An implication of the latter is as follows:</p>
<p >Any user source code line that nullifies a <code>Ptr</code> (<code>shared_ptr</code>) handle to <code>*this</code> should be seen as potentially <em>synchoronously</em> invoking this dtor. (By nullification we mean <code>.reset()</code> and anything else that makes the <code>Ptr</code> null. For example destroying a <code>vector&lt;Ptr&gt;</code> that contains a <code>Ptr</code> pointing to <code>*this</code> = nullification.) Therefore, if a nullification statement can possibly make the ref-count reach 0, then the user must zealously protect that statement from running concurrently with another send/receive API call on <code>*this</code>. That is to say, informally: When ensuring thread safety with respect to concurrent access to a <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a>, don't forget that the destructor also is a write-type of access, and that nullifying a <code>Ptr</code> handle to it can synchronously invoke it.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae6d2627aa6ee2216cddbc801a28fa268" title="Destroys this peer endpoint which will end the conceptual incoming-direction pipe (in PEER state,...">Native_handle_receiver::~Native_handle_receiver()</a>: sister concept with essentially equal requirements. </dd>
<dd>
<a class="el" href="classipc_1_1transport_1_1Native__socket__stream.html#a1ff9e6811c0d662a6a960602be5926e0" title="Implements Native_handle_sender and Native_handle_receiver APIs at the same time, per their concept c...">Native_socket_stream::~Native_socket_stream()</a>: implements concept (also implements just-mentioned sister concept). </dd></dl>

</div>
</div>
<h2 class="groupheader">Member Function Documentation</h2>
<a id="a4c92fe4e43ddf819a2c767cc53cbe477" name="a4c92fe4e43ddf819a2c767cc53cbe477"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a4c92fe4e43ddf819a2c767cc53cbe477">&#9670;&nbsp;</a></span>async_end_sending()</h2>

<div class="memitem">
<div class="memproto">
<div class="memtemplate">
template&lt;typename Task_err &gt; </div>
      <table class="memname">
        <tr>
          <td class="memname">bool ipc::transport::Native_handle_sender::async_end_sending </td>
          <td>(</td>
          <td class="paramtype">Task_err &amp;&amp;&#160;</td>
          <td class="paramname"><em>on_done_func</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Equivalent to <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> but sends a graceful-close message instead of the usual payload; the opposing peer's <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a> shall receive it reliably and in-order via <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">Native_handle_receiver::async_receive_native_handle()</a> in the form of <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> = <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297aad44f87d53255ba573d57086dfeab805" title="Will not receive message: either opposing user sent graceful-close via API.">error::Code::S_RECEIVES_FINISHED_CANNOT_RECEIVE</a>. </p>
<p >If invoked after already invoking <code>*end_sending()</code>, the method shall no-op and return <code>false</code> and neither an exception nor truthy <code>*err_code</code>. Otherwise it shall return <code>true</code> &ndash; but potentially emit a truthy <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> (if an error is detected).</p>
<p >In addition: if <code>*this</code> is not in PEER state (in particular if it is default-cted or moved-from), returns <code>false</code> immediately instead and otherwise no-ops (logging aside).</p>
<p >Informally one should think of <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a4c92fe4e43ddf819a2c767cc53cbe477" title="Equivalent to send_native_handle() but sends a graceful-close message instead of the usual payload; t...">async_end_sending()</a> as just another message, which is queued after preceding ones; but: it is the <em>last</em> message to be queued by definition. It's like an EOF or a TCP-FIN.</p>
<h3>Synchronicity/blockingness guarantees</h3>
<p ><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a4c92fe4e43ddf819a2c767cc53cbe477" title="Equivalent to send_native_handle() but sends a graceful-close message instead of the usual payload; t...">async_end_sending()</a> is, unlike <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a>, formally asynchronous. The reason for this, and the expected use pattern of <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a4c92fe4e43ddf819a2c767cc53cbe477" title="Equivalent to send_native_handle() but sends a graceful-close message instead of the usual payload; t...">async_end_sending()</a> in the context of preceding <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> calls, is found in the doc header for <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">Native_handle_sender::send_native_handle()</a>. We omit further discussion here.</p>
<h3>Error semantics</h3>
<p >This section discusses the case where <code>true</code> is returned, meaning <code>*end_sending()</code> had not already been called.</p>
<p >An <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> is generated and passed as the sole arg to <code>on_done_func()</code>. A falsy one indicates success. A truthy one indicates failure; but in particular:</p><ul>
<li><a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297afe29343445a7bf167cc186a44bd2c6ed" title="Async completion handler is being called prematurely, because underlying object is shutting down,...">error::Code::S_OBJECT_SHUTDOWN_ABORTED_COMPLETION_HANDLER</a> (destructor called, canceling all pending ops; spiritually identical to <code>boost::asio::error::operation_aborted</code>);</li>
<li>other arbitrary codes are possible, as with <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a>.</li>
</ul>
<p >Reminder: By the nature of <code>on_done_func()</code>, the pipe is finished regardless of whether it receives a success or non-success <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a>.</p>
<h3>Thread safety</h3>
<p >The notes for <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> apply.</p>
<p >The semantic re. calling <code>*end_sending()</code> after already having called it and having that exclusively return <code>false</code> and do nothing was a judgment call. As of this writing there's a long-ish comment at the top of of <code>"sync_io::Native_socket_stream::Impl::*end_sending()"</code>" body discussing why I (ygoldfel) went that way. </p>
<dl class="tparams"><dt>Template Parameters</dt><dd>
  <table class="tparams">
    <tr><td class="paramname">Task_err</td><td>A functor type with signature identical to <code>flow::async::Task_asio_err</code>. </td></tr>
  </table>
  </dd>
</dl>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">on_done_func</td><td>See above. This shall be invoked from an unspecified thread that is not the calling thread. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><code>false</code> if and only if <em>either</em> <code>*this</code> is not in PEER (connected, transmitting) state, <em>or</em> <code>*end_sending()</code> has already been called before (so this is a no-op, in both cases). Otherwise <code>true</code>. </dd></dl>

</div>
</div>
<a id="a8a2f1282c18faec36aabf29c99b87054" name="a8a2f1282c18faec36aabf29c99b87054"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a8a2f1282c18faec36aabf29c99b87054">&#9670;&nbsp;</a></span>auto_ping()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">bool ipc::transport::Native_handle_sender::auto_ping </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="namespaceipc_1_1util.html#ac66141280c3b7295a86b65209f31cc58">util::Fine_duration</a>&#160;</td>
          <td class="paramname"><em>period</em> = <code>default_value</code></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>In PEER state: Irreversibly enables periodic auto-pinging of opposing receiver with low-level messages that are ignored except that they reset any idle timer as enabled via <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#a174ee15818a8bda361bdc40f094faac9" title="In PEER state: Irreversibly enables a conceptual idle timer whose potential side effect is,...">Native_handle_receiver::idle_timer_run()</a> (or similar). </p>
<p >Auto-pings, at a minimum, shall be sent (subject to internal low-level transport would-block conditions) at the following times:</p><ul>
<li>as soon as possible after a successful <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a8a2f1282c18faec36aabf29c99b87054" title="In PEER state: Irreversibly enables periodic auto-pinging of opposing receiver with low-level message...">auto_ping()</a> call; and subsequently:</li>
<li>at such times as to ensure that the time between 2 adjacent sends of <em>any</em> message is no more than <code>period</code>, until <code>*end_sending()</code> (if any) or error (if any). To clarify the 2nd point: If user messages are being sent already, an auto-ping may not be required or may be delayed until the last-sent message plus <code>period</code>). The implementation shall strive not to wastefully add auto-ping traffic unnecessary to this goal but is not <em>required</em> to do so. However, per the 1st point, an auto-ping shall be sent near <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a8a2f1282c18faec36aabf29c99b87054" title="In PEER state: Irreversibly enables periodic auto-pinging of opposing receiver with low-level message...">auto_ping()</a> time to establish a baseline.</li>
</ul>
<p >If <code>*this</code> is not in PEER state (in particular if it is default-cted or moved-from), returns <code>false</code> immediately instead and otherwise no-ops (logging aside). If <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a8a2f1282c18faec36aabf29c99b87054" title="In PEER state: Irreversibly enables periodic auto-pinging of opposing receiver with low-level message...">auto_ping()</a> has already been called successfuly, subsequently it will return <code>false</code> and no-op (logging aside). If <code>*end_sending()</code> has been called succesfully, <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a8a2f1282c18faec36aabf29c99b87054" title="In PEER state: Irreversibly enables periodic auto-pinging of opposing receiver with low-level message...">auto_ping()</a> will return <code>false</code> and no-op (logging side).</p>
<h3>Behavior past <code>*end_sending()</code></h3>
<p >As noted: <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a8a2f1282c18faec36aabf29c99b87054" title="In PEER state: Irreversibly enables periodic auto-pinging of opposing receiver with low-level message...">auto_ping()</a> returns <code>false</code> and no-ops if invoked after successful <code>*end_sending()</code>. Rationale: If <code>*end_sending()</code> has been called, then the receiver shall (assuming no other error) receive graceful-close (and hose the in-pipe as a result) as soon as possible, or it has already received it (and hosed the pipe). Therefore any potential "further" hosing of the pipe due to idle timer would be redundant and ignored anyway given the nature of the <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a> (and similar) API.</p>
<h3>Thread safety</h3>
<p >The notes for <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> apply.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">period</td><td>Pinging occurs so as to cause the opposing receiver to receive <em>a</em> message (whether auto-ping or user message) at least this frequently, subject to limitations of the low-level transport. The optional default is chosen by the impl to most reasonably work with the opposing <code>idle_timer_run()</code> to detect a zombified/overloaded peer. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><code>false</code> if <code>*this</code> is not in PEER (connected, transmitting) state, or if already called successfully in <code>PEER</code> state, or if <code>*end_sending()</code> was called successfully in <code>PEER</code> state; otherwise <code>true</code>. </dd></dl>

</div>
</div>
<a id="aa3c2953f7f8a48b8a0cbf49652fb6d41" name="aa3c2953f7f8a48b8a0cbf49652fb6d41"></a>
<h2 class="memtitle"><span class="permalink"><a href="#aa3c2953f7f8a48b8a0cbf49652fb6d41">&#9670;&nbsp;</a></span>end_sending()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">bool ipc::transport::Native_handle_sender::end_sending </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Equivalent to <code>async_end_sending(F)</code> wherein <code>F()</code> does nothing. </p>
<p >Informally: If one uses this overload, it is impossible to guarantee everything queued has actually been sent, as <code>on_done_func()</code> is the only mechanism for this. Most likely this is only useful for test or proof-of-concept code; production-level robustness typically requires one to ensure everything queued has been sent. Alternatively the user's application-level protocol may already guarantee the message exchange has completed (e.g., by receiving an acknowledgment message of some sort) &ndash; but in that case one can simply not call <code>*end_sending()</code> at all.</p>
<dl class="section return"><dt>Returns</dt><dd>Same as in <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a4c92fe4e43ddf819a2c767cc53cbe477" title="Equivalent to send_native_handle() but sends a graceful-close message instead of the usual payload; t...">async_end_sending()</a>. </dd></dl>

</div>
</div>
<a id="a7de1a7f689cfdd926580cf92131896bb" name="a7de1a7f689cfdd926580cf92131896bb"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a7de1a7f689cfdd926580cf92131896bb">&#9670;&nbsp;</a></span>operator=()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html">Native_handle_sender</a> &amp; ipc::transport::Native_handle_sender::operator= </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html">Native_handle_sender</a> &amp;&amp;&#160;</td>
          <td class="paramname"><em>src</em></td><td>)</td>
          <td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>Move-assigns from <code>src</code>; <code>*this</code> acts as if destructed; <code>src</code> becomes as-if default-cted (therefore in NULL state). </p>
<p >No-op if <code>&amp;src == this</code>.</p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#aa2354a74bc6cdff9389d0b7b642fbadd" title="Destroys this peer endpoint which will end the conceptual outgoing-direction pipe (in PEER state,...">~Native_handle_sender()</a>.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">src</td><td>Source object. For reasonable uses of <code>src</code> after this ctor returns: see default ctor doc header. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><code>*this</code>. </dd></dl>

</div>
</div>
<a id="a74452bf96477a7b971e187c67703e8d5" name="a74452bf96477a7b971e187c67703e8d5"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a74452bf96477a7b971e187c67703e8d5">&#9670;&nbsp;</a></span>send_meta_blob_max_size()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">size_t ipc::transport::Native_handle_sender::send_meta_blob_max_size </td>
          <td>(</td>
          <td class="paramname"></td><td>)</td>
          <td> const</td>
        </tr>
      </table>
</div><div class="memdoc">

<p>In PEER state: Returns max <code>meta_blob.size()</code> such that <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> shall not fail due to too-long payload with <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297ac416e988563e44bf15fc6a81743eef53" title="User called an API with 1 or more arguments against the API spec.">error::Code::S_INVALID_ARGUMENT</a>. </p>
<p >Always the same value once in PEER state. The opposing Blob_receiver::receive_meta_blob_max_size() shall return the same value (in the opposing object potentially in a different process).</p>
<p >If <code>*this</code> is not in PEER state (in particular if it is default-cted or moved-from), returns zero; else a positive value.</p>
<dl class="section return"><dt>Returns</dt><dd>See above. </dd></dl>

</div>
</div>
<a id="ac96b0aa01c286d525f9dcfa6dacc4220" name="ac96b0aa01c286d525f9dcfa6dacc4220"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ac96b0aa01c286d525f9dcfa6dacc4220">&#9670;&nbsp;</a></span>send_native_handle()</h2>

<div class="memitem">
<div class="memproto">
      <table class="memname">
        <tr>
          <td class="memname">bool ipc::transport::Native_handle_sender::send_native_handle </td>
          <td>(</td>
          <td class="paramtype"><a class="el" href="namespaceipc_1_1transport.html#a7ee4551983d9df16ec16a3139bac50e8">Native_handle</a>&#160;</td>
          <td class="paramname"><em>hndl_or_null</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype">const <a class="el" href="namespaceipc_1_1util.html#ae0be7edba7e30ffa3f8b742af621f2ab">util::Blob_const</a> &amp;&#160;</td>
          <td class="paramname"><em>meta_blob</em>, </td>
        </tr>
        <tr>
          <td class="paramkey"></td>
          <td></td>
          <td class="paramtype"><a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89">Error_code</a> *&#160;</td>
          <td class="paramname"><em>err_code</em> = <code>0</code>&#160;</td>
        </tr>
        <tr>
          <td></td>
          <td>)</td>
          <td></td><td></td>
        </tr>
      </table>
</div><div class="memdoc">

<p>In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order, to the opposing peer; the message consists of the provided native handle (if supplied); or the provided binary blob (if supplied); or both (if both supplied). </p>
<p >The opposing peer's paired <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order receivin...">Native_handle_receiver</a> shall receive it reliably and in-order via <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">Native_handle_receiver::async_receive_native_handle()</a>.</p>
<p >If <code>*this</code> is not in PEER state (in particular if it is default-cted or moved-from), returns <code>false</code> immediately instead and otherwise no-ops (logging aside).</p>
<p >Providing neither a handle nor a blob results in undefined behavior (assertion may trip). To <em>not</em> supply a handle, provide object with <code>.null() == true</code>. To <em>not</em> supply a blob, provide a buffer with <code>.size() == 0</code>.</p>
<h3>Blob copying behavior; synchronicity/blockingness guarantees</h3>
<p >If a blob is provided, it need only be valid until this method returns. The implementation shall, informally, strive to <em>not</em> save a copy of the blob (except into the low-level transport mechanism); but it is <em>allowed</em> to save it if required, such as if the low-level transport mechanism encounteres a would-block condition.</p>
<p >This means, to the user, that this method is <em>both</em> non-blocking <em>and</em> synchronous <em>and</em> it must not refuse to send and return any conceptual would-block error (unlike, say, with a typical networked TCP socket API). Informally, the implementation must deal with any (typically quite rare) internal low-level would-block condition internally.</p>
<p >However! Suppose <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> returns without error. This concept does <em>not</em> guarantee the message has been passed to the low-level transport at <em>this</em> point in time (informally it shall strive to make that happen in most cases however). A low-level would-block condition may cause it to be deferred. If one invokes <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#aa2354a74bc6cdff9389d0b7b642fbadd" title="Destroys this peer endpoint which will end the conceptual outgoing-direction pipe (in PEER state,...">~Native_handle_sender()</a> (dtor), the message may never be sent.</p>
<p >However (part II)! It <em>is</em> guaranteed to have been passed to the transport once <code>*end_sending()</code> has been invoked, <em>and</em> its <code>on_done_func()</code> (if any) callback has been called. Therefore the expected use pattern is as follows:</p><ul>
<li>Obtain a connected <code><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a></code> via factory.</li>
<li>Invoke <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> synchronously, hopefully without error.</li>
<li>(Repeat as needed for more such messages.)</li>
<li>Invoke <code>async_end_sending(F)</code> or <code><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#aa3c2953f7f8a48b8a0cbf49652fb6d41" title="Equivalent to async_end_sending(F) wherein F() does nothing.">end_sending()</a></code> (to send graceful-close).</li>
<li>In <code>F()</code> destroy the <code><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a></code> (its dtor is invoked).<ul>
<li><code>F()</code> is invoked only once all queued messages, and the graceful-close, have been sent.</li>
</ul>
</li>
</ul>
<h3>Error semantics</h3>
<p >Firstly: See <code>flow::Error_code</code> docs for error reporting semantics (including the exception/code dichotomy).</p>
<p >Secondly: If the generated <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> is <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297ac416e988563e44bf15fc6a81743eef53" title="User called an API with 1 or more arguments against the API spec.">error::Code::S_INVALID_ARGUMENT</a>:</p><ul>
<li>This refers to an invalid argument to <em>this</em> method invocation. This does <em>not</em> hose the pipe: further sends, etc., may be attempted with reasonable hope they will succeed.<ul>
<li><a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a74452bf96477a7b971e187c67703e8d5" title="In PEER state: Returns max meta_blob.size() such that send_native_handle() shall not fail due to too-...">send_meta_blob_max_size()</a> is the limit for <code>meta_blob.size()</code>. Exceeding it leads to <code>S_INVALID_ARGUMENT</code>.<ul>
<li>This interacts with the opposing <a class="el" href="classipc_1_1transport_1_1Native__handle__receiver.html#ae4ac1685f00467a6516f9f24f5d8a280" title="In PEER state: Asynchronously awaits one discrete message – as sent by the opposing peer via Native_h...">Native_handle_receiver::async_receive_native_handle()</a> in a subtle way. See "Blob underflow semantics" in that class concept's doc header.</li>
</ul>
</li>
<li>At the impl's discretion, other conditions <em>may</em> lead to <code>S_INVALID_ARGUMENT</code>. If so they must be documented.</li>
</ul>
</li>
</ul>
<p >Thirdly: All other non-success <code>Error_code</code>s generated should indicate the pipe is now indeed hosed; the user can count on the pipe being unusable from that point on. (It is recommended they cease to use the pipe and invoke the destructor to free resources.) If such a non-success code is emitted, the same one shall be emitted by all further <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> and <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#a4c92fe4e43ddf819a2c767cc53cbe477" title="Equivalent to send_native_handle() but sends a graceful-close message instead of the usual payload; t...">async_end_sending()</a> on <code>*this</code>.</p>
<p >In particular <a class="el" href="namespaceipc_1_1transport_1_1error.html#adfef15ef4e76cc55d652fbd9c2797297a42d41c622e92e9053177ba73e75633fe" title="Will not send message: local user already ended sending via API marking this.">error::Code::S_SENDS_FINISHED_CANNOT_SEND</a> shall indicate that <em>this</em> method invocation occurred after invoking <code>*end_sending()</code> earlier.</p>
<p >No would-block-like error condition shall be emitted.</p>
<p >Lastly: The implementation is allowed to return a non-<code>INVALID_ARGUMENT</code> <a class="el" href="namespaceipc.html#aa3192e586cc45d3e7c22463bf2760f89" title="Short-hand for flow::Error_code which is very common.">Error_code</a> in <em>this</em> invocation even though the true cause is a <em>previous</em> invocation of <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a>. Informally this may occur (probably in rare circumstances) if internally the handling of a previous call had to be deferred due to a low-level would-block condition; in that case the resulting problem is to be reported opportunistically with the next call. This allows for the non-blocking/synchronous semantics without the need to make <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html#ac96b0aa01c286d525f9dcfa6dacc4220" title="In PEER state: Synchronously, non-blockingly sends one discrete message, reliably/in-order,...">send_native_handle()</a> asynchronous.</p>
<h3>Thread safety</h3>
<p >You may call this from any thread. It is <em>not</em> required to be safe to call concurrently with any <a class="el" href="classipc_1_1transport_1_1Native__handle__sender.html" title="A documentation-only concept defining the behavior of an object capable of reliably/in-order sending ...">Native_handle_sender</a> API, including this one and the destructor, invoked on <code>*this</code>.</p>
<dl class="params"><dt>Parameters</dt><dd>
  <table class="params">
    <tr><td class="paramname">hndl_or_null</td><td>A native handle (a/k/a FD) to send; or none if <code>hndl_or_null.null() == true</code>. </td></tr>
    <tr><td class="paramname">meta_blob</td><td>A binary blob to send; or none if <code>meta_blob.size() == 0</code>. </td></tr>
    <tr><td class="paramname">err_code</td><td>See above. </td></tr>
  </table>
  </dd>
</dl>
<dl class="section return"><dt>Returns</dt><dd><code>false</code> if <code>*this</code> is not in PEER (connected, transmitting) state; otherwise <code>true</code>. </dd></dl>

</div>
</div>
<h2 class="groupheader">Member Data Documentation</h2>
<a id="a840003f2f91ef73f319e0e6b5e7ab435" name="a840003f2f91ef73f319e0e6b5e7ab435"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a840003f2f91ef73f319e0e6b5e7ab435">&#9670;&nbsp;</a></span>S_RESOURCE_TYPE_ID</h2>

<div class="memitem">
<div class="memproto">
<table class="mlabels">
  <tr>
  <td class="mlabels-left">
      <table class="memname">
        <tr>
          <td class="memname">const <a class="el" href="namespaceipc_1_1transport.html#a33de1c256addb3964b839dc2dd407d24">Shared_name</a> ipc::transport::Native_handle_sender::S_RESOURCE_TYPE_ID</td>
        </tr>
      </table>
  </td>
  <td class="mlabels-right">
<span class="mlabels"><span class="mlabel">static</span></span>  </td>
  </tr>
</table>
</div><div class="memdoc">

<p>Shared_name relative-folder fragment (no separators) identifying this resource type. Equals <code>_receiver</code>'s. </p>

<p class="definition">Definition at line <a class="el" href="native__handle__transport_8hpp_source.html#l00165">165</a> of file <a class="el" href="native__handle__transport_8hpp_source.html">native_handle_transport.hpp</a>.</p>

</div>
</div>
<hr/>The documentation for this class was generated from the following file:<ul>
<li>transport/<a class="el" href="native__handle__transport_8hpp_source.html">native_handle_transport.hpp</a></li>
</ul>
</div><!-- contents -->
<!-- start footer part -->
<hr class="footer"/><address class="footer"><small>
Generated on Thu May 2 2024 23:56:39 for Flow-IPC by&#160;<a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.4
</small></address>
</body>
</html>
